home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / p_man / cat3 / libelfutil / xlate_pro_init.z / xlate_pro_init
Text File  |  1998-10-30  |  18KB  |  330 lines
  1.  
  2.  
  3.  
  4. XXXXLLLLAAAATTTTEEEE____PPPPRRRROOOO____IIIINNNNIIIITTTT((((3333EEEE))))                                          XXXXLLLLAAAATTTTEEEE____PPPPRRRROOOO____IIIINNNNIIIITTTT((((3333EEEE))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _xxxx_llll_aaaa_tttt_eeee______pppp_rrrr_oooo______iiii_nnnn_iiii_tttt - open translation section creator
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_eeee_llll_ffff_...._hhhh_>>>>
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_llll_iiii_bbbb_eeee_llll_ffff_...._hhhh_>>>>
  14.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_dddd_wwww_aaaa_rrrr_ffff_...._hhhh_>>>>
  15.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_llll_iiii_bbbb_dddd_wwww_aaaa_rrrr_ffff_...._hhhh_>>>>
  16.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_cccc_mmmm_pppp_llll_rrrr_ssss_////_xxxx_llll_aaaa_tttt_eeee_...._hhhh_>>>>
  17.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_llll_iiii_bbbb_XXXX_llll_aaaa_tttt_eeee_...._hhhh_>>>>
  18.      _iiii_nnnn_tttt _xxxx_llll_aaaa_tttt_eeee______pppp_rrrr_oooo______iiii_nnnn_iiii_tttt_(((( _xxxx_llll_aaaa_tttt_eeee______tttt_aaaa_bbbb_llll_eeee______pppp_rrrr_oooo  _****_rrrr_eeee_tttt_uuuu_rrrr_nnnn_eeee_dddd______tttt_aaaa_bbbb_llll_eeee______pppp_oooo_iiii_nnnn_tttt_eeee_rrrr_,,,,
  19.        _xxxx_llll_aaaa_tttt_eeee______tttt_aaaa_bbbb_llll_eeee_kkkk_iiii_nnnn_dddd  _tttt_aaaa_bbbb_llll_eeee_kkkk_iiii_nnnn_dddd_,,,,
  20.        _xxxx_llll_aaaa_tttt_eeee______tttt_aaaa_bbbb_llll_eeee______cccc_oooo_nnnn  _cccc_oooo_mmmm_pppp_oooo_ssss_eeee______wwww_iiii_tttt_hhhh______tttt_aaaa_bbbb_llll_eeee_,,,,
  21.        _iiii_nnnn_tttt             _iiii_ssss_6666_4444_bbbb_iiii_tttt_))))_;;;;
  22.  
  23. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  24.      These are used to get (open) a handle which assists in producing a
  25.      translation table section.  The functions available do not themselves
  26.      write anything to disk. Instead they create a byte stream which the
  27.      calling application can write to an Elf file as appropriate.
  28.  
  29.      The handle allows one to call any of the producer functions.
  30.  
  31.      _x_l_a_t_e__p_r_o__i_n_i_t takes as arguments:
  32.  
  33.      _r_e_t_u_r_n_e_d__t_a_b_l_e__p_o_i_n_t_e_r
  34.              is a pointer to a producer table handle.  If the call to
  35.              _x_l_a_t_e__p_r_o__i_n_i_t is successful, the handle pointed to is set a
  36.              valid producer library handle.
  37.  
  38.      _t_a_b_l_e_k_i_n_d
  39.              which must be one of the types of table defined in the
  40.              enumeration:  order-preserving, size-preserving, or general.  See
  41.              <_l_i_b_X_l_a_t_e._h>.  The order-preserving and size-preserving cases
  42.              allow a slightly more compact disk representation to be used.
  43.              See below for more discussion of the table choices.
  44.  
  45.      _c_o_m_p_o_s_e__w_i_t_h__t_a_b_l_e
  46.              must be 0 or a valid open handle on a (non-debug) translate table
  47.              section.  If 0 (the NULL pointer) then the byte stream prepared
  48.              by the library will depend solely on the input from producer
  49.              calls.  A 0 argument means that there will be a single byte
  50.              stream available in the output.  If an open consumer handle is
  51.              passed in then the library will _c_o_m_p_o_s_e the information passed in
  52.              thru producer calls with the information from _c_o_m_p_o_s_e__w_i_t_h__t_a_b_l_e
  53.              and will make available two byte stream outputs:  one will be the
  54.              composed translation table representing all translations and the
  55.              second (debug) table will represent solely the information passed
  56.              in thru producer calls.  _x_l_a_t_e__p_r_o__d_i_s_k__h_e_a_d_e_r(3) gives access to
  57.              the normal (standard) byte stream if called with
  58.              _X_L_A_T_E__P_R_O__S_T_A_N_D_A_R_D__S_E_T_U_P.  _x_l_a_t_e__p_r_o__d_i_s_k__h_e_a_d_e_r(3) gives access
  59.              to the debug stream if called with _X_L_A_T_E__P_R_O__S_T_A_N_D_A_R_D__S_E_T_U_P: the
  60.  
  61.  
  62.                                                                         PPPPaaaaggggeeee 1111
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69. XXXXLLLLAAAATTTTEEEE____PPPPRRRROOOO____IIIINNNNIIIITTTT((((3333EEEE))))                                          XXXXLLLLAAAATTTTEEEE____PPPPRRRROOOO____IIIINNNNIIIITTTT((((3333EEEE))))
  70.  
  71.  
  72.  
  73.              debug stream will only have non-zero length if _c_o_m_p_o_s_e__w_i_t_h__t_a_b_l_e
  74.              is a non-NULL consumer table handle.
  75.  
  76.      _i_s_6_4_b_i_t informs the producer library whether the translate table is for a
  77.              64 or 32 bit executable or DSO.  Pass in 0 if for a 32-bit
  78.              executable or DSO.  Pass in 1 if for a 64-bit executable or DSO.
  79.              The flag must match (in the sense of being 32 or 64 bit) the 64-
  80.              bitness of the data in the _c_o_m_p_o_s_e__w_i_t_h__t_a_b_l_e .
  81.  
  82.      Use -lelfutil -lelf on the link command line to link  in _l_i_b_e_l_f_u_t_i_l.
  83.  
  84. TTTTaaaabbbblllleeee KKKKiiiinnnnddddssss
  85.      The table kind argument specifies characteristics of the addresses and
  86.      ranges passed in to the producer functions.  If there is no Table
  87.      Composition (because _c_o_m_p_o_s_e__w_i_t_h__t_a_b_l_e us NULL) then the _t_a_b_l_e_k_i_n_d
  88.      argument is the output non-debug table kind (and there is no debug table
  89.      produced).  If there is Table Composition because _c_o_m_p_o_s_e__w_i_t_h__t_a_b_l_e is
  90.      non-NULL then the table kind of the created table may not be identical to
  91.      that specified in the argument.
  92.  
  93.      It is the producing application's responsibility to tell the truth about
  94.      the input.  If the application specifies that the input is order-
  95.      preserving and then does _x_l_a_t_e__p_r_o__a_d_d__r_a_n_g_e calls which violate that
  96.      assertion the library may or may not detect the violation. The resulting
  97.      table is not going to be correct in such a case.
  98.  
  99.      An order-preserving table (_x_l_a_t_e__t_k__p_r_e_s_e_r_v_e__s_i_z_e) is created by calls to
  100.      _x_l_a_t_e__p_r_o__a_d_d__r_a_n_g_e in which successive new-addresses are increasing and
  101.      successive old-addresses are increasing.
  102.  
  103.      A size-preserving table (_x_l_a_t_e__t_k__p_r_e_s_e_r_v_e__s_i_z_e) is created by calls to
  104.      _x_l_a_t_e__p_r_o__a_d_d__r_a_n_g_e in which the new-range and the old-range are
  105.      identical values (in other words, the new and old instruction streams are
  106.      identical length).  The library assumes that the new-instruction
  107.      addresses form a strictly increasing sequence (the old-instruction
  108.      addresses ordinarily do not).
  109.  
  110.      A general table is any table not fitting one of the two special cases
  111.      above.  The library assumes that the new-instruction addresses form a
  112.      strictly increasing sequence (so that while the library can handle
  113.      "general" transformations, the order that the transformations are
  114.      presented to _x_l_a_t_e__p_r_o__a_d_d__r_a_n_g_e is restricted to be in increasing new-
  115.      address order).
  116.  
  117. TTTTaaaabbbblllleeee CCCCoooommmmppppoooossssiiiittttiiiioooonnnn
  118.      Table Composition allows the application of a (potentially unlimited)
  119.      series of transformation tools while preserving the ability to use a
  120.      debugger or other tool needing to correctly associate text address in
  121.      memory with the symbolic information and with the original untransformed
  122.      text addresses.  If _c_o_m_p_o_s_e__w_i_t_h__t_a_b_l_e is NULL then there is no Table
  123.      Composition done (there being no input table provided to compose with).
  124.  
  125.  
  126.  
  127.  
  128.                                                                         PPPPaaaaggggeeee 2222
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135. XXXXLLLLAAAATTTTEEEE____PPPPRRRROOOO____IIIINNNNIIIITTTT((((3333EEEE))))                                          XXXXLLLLAAAATTTTEEEE____PPPPRRRROOOO____IIIINNNNIIIITTTT((((3333EEEE))))
  136.  
  137.  
  138.  
  139.      If _c_o_m_p_o_s_e__w_i_t_h__t_a_b_l_e is non-NULL then table composition will occur.
  140.      Composing a size-preserving with a size-preserving table results in a
  141.      size-preserving table.  Composing an order-preserving with an order-
  142.      preserving table results in a order-preserving table.  Any other
  143.      composition results in a general table.
  144.  
  145.      The application doing the transformation should treat its composition as
  146.      the only composition and should treat the executable text as being
  147.      transformed.  The library does the composition.
  148.  
  149.      Composition of addresses is done by the library.  The following describes
  150.      how each of the fields in the each of the translate headers is treated.
  151.  
  152.      _h_d__v_e_r_s_i_o_n
  153.              will be the same in both the debug and non-debug tables output.
  154.  
  155.      _h_d__t_a_b_l_e_k_i_n_d
  156.              will be taken directly from the _t_a_b_l_e_k_i_n_d argument for the debug
  157.              table.  For the non-debug table the value will be as described in
  158.              _T_a_b_l_e _K_i_n_d_s above.
  159.  
  160.      _h_d__b_l_o_c_k__s_i_z_e
  161.              For both the debug and non-debug tables the library supplies
  162.              this.  (At this writing it is a fixed value of 4096).
  163.  
  164.      _h_d__n_u_m__b_l_o_c_k_s
  165.              is set appropriately by the library for each table output.
  166.  
  167.      _h_d__n_u_m__e_n_t_r_i_e_s
  168.              is set appropriately by the library for each table output.
  169.  
  170.      _h_d__n_e_w__a_d_d_r__l_o_w
  171.              For both the tables this is the same value: the lowest of the new
  172.              addresses.
  173.  
  174.      _h_d__n_e_w__a_d_d_r__h_i_g_h
  175.              For both the tables this is the same value: the highest of the
  176.              new addresses.
  177.  
  178.      _h_d__o_l_d__a_d_d_r__l_o_w
  179.              For the non-debug table, this is the copied from the
  180.              _h_d__o_l_d__a_d_d_r__l_o_w of the input table-to-be-composed-with.  For the
  181.              debug table, this is calculated from the ranges seen by
  182.              _x_l_a_t_e__p_r_o__a_d_d__r_a_n_g_e.
  183.  
  184.      _h_d__o_l_d__a_d_d_r__h_i_g_h
  185.              For the non-debug table, this is the copied from the
  186.              _h_d__o_l_d__a_d_d_r__h_i_g_h of the input table-to-be-composed-with.  For the
  187.              debug table, this is calculated from the ranges seen by
  188.              _x_l_a_t_e__p_r_o__a_d_d__r_a_n_g_e.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                                                                         PPPPaaaaggggeeee 3333
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201. XXXXLLLLAAAATTTTEEEE____PPPPRRRROOOO____IIIINNNNIIIITTTT((((3333EEEE))))                                          XXXXLLLLAAAATTTTEEEE____PPPPRRRROOOO____IIIINNNNIIIITTTT((((3333EEEE))))
  202.  
  203.  
  204.  
  205.      _h_d__d_a_t_a__m_o_v_e_d
  206.              For the debug table, this is taken from the _x_l_a_t_e__p_r_o__a_d_d__i_n_f_o
  207.              call (defaults to 0).  For the non-debug table, the output value
  208.              is the sum (using 32 bit arithmetic for 32 bit programs and 64
  209.              bit arithmetic for 64 bit programs) of the from the input table-
  210.              to-be-composed-with and the _d_a_t_a__m_o_v_e_d argument of the
  211.              _x_l_a_t_e__p_r_o__a_d_d__i_n_f_o call.
  212.  
  213.      _h_d__s_t_a_r_t_u_p__f_w_a
  214.              For the debug table, this is taken from the appropriate
  215.              _x_l_a_t_e__p_r_o__a_d_d__i_n_f_o call argument (defaults to 0).  For the non-
  216.              debug table, take that argument if non-zero and if the
  217.              _x_l_a_t_e__p_r_o__a_d_d__i_n_f_o is not provided or the argument is 0 take the
  218.              value from the _h_d__s_t_a_r_t_u_p__f_w_a from the input table-to-be-
  219.              composed-with.
  220.  
  221.      _h_d__s_t_a_r_t_u_p__l_w_a
  222.              For the debug table, this is taken from the appropriate
  223.              _x_l_a_t_e__p_r_o__a_d_d__i_n_f_o call argument (defaults to 0).  For the non-
  224.              debug table, take that argument if non-zero and if the
  225.              _x_l_a_t_e__p_r_o__a_d_d__i_n_f_o is not provided or the argument is 0 take the
  226.              value from the _h_d__s_t_a_r_t_u_p__l_w_a from the input table-to-be-
  227.              composed-with.
  228.  
  229.      _h_d__o_l_d__t_e_x_t__e_x_i_s_t_s
  230.              For the non-debug table, take the value from the input table-to-
  231.              be-composed with.  For the debug table, take the value from the
  232.              _x_l_a_t_e__p_r_o__a_d_d__i_n_f_o call argument (defaults to 0).
  233.  
  234.      _h_d__o_l_d__t_e_x_t__a_l_l_o_c
  235.              For the non-debug table, take the value from the input table-to-
  236.              be-composed with.  For the debug table, take the value from the
  237.              _x_l_a_t_e__p_r_o__a_d_d__i_n_f_o call argument (defaults to 0).
  238.  
  239.      _h_d__r_e_g__i_n_f_o__s_i_z_e
  240.              For the debug table, take the data provided with
  241.              _x_l_a_t_e__p_r_o__a_d_d__r_e_g__i_n_f_o calls.  For the non-debug table, add the
  242.              data provided with _x_l_a_t_e__p_r_o__a_d_d__r_e_g__i_n_f_o calls to the end of the
  243.              data in the input table-to-be-composed-with.  This behavior is
  244.              incorrect, since any DW_CFA_set_loc or DW_CFA_advance_loc
  245.              operations in the table-to-be-composed-with are not updated
  246.              appropriately as of this writing.
  247.  
  248. FFFFIIIILLLLEEEESSSS
  249.      /usr/include/libXlate.h
  250.      /usr/include/cmplrs/xlate.h
  251.      /usr/include/elf.h
  252.      /usr/include/dwarf.h
  253.      /usr/include/libdwarf.h
  254.      /usr/lib/libelfutil.a
  255.  
  256.  
  257.  
  258.  
  259.  
  260.                                                                         PPPPaaaaggggeeee 4444
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267. XXXXLLLLAAAATTTTEEEE____PPPPRRRROOOO____IIIINNNNIIIITTTT((((3333EEEE))))                                          XXXXLLLLAAAATTTTEEEE____PPPPRRRROOOO____IIIINNNNIIIITTTT((((3333EEEE))))
  268.  
  269.  
  270.  
  271. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  272.      Returns XLATE_TB_STATUS_NO_ERROR (0) on success.  In case of error, a
  273.      negative number is returned indicating the error.  In case of error,
  274.      nothing is returned thru the pointer arguments which would return values
  275.      on successful call (values might have been changed thru these pointers
  276.      but any such changes are not meaningful).
  277.  
  278.      _X_L_A_T_E__T_B__S_T_A_T_U_S__B_A_D__T_A_B_L_E_K_I_N_D
  279.              means that the passed in _t_a_b_l_e_k_i_n_d is not one of the three
  280.              defined values.
  281.  
  282.      _X_L_A_T_E__T_B__S_T_A_T_U_S__A_L_L_O_C__F_A_I_L
  283.              means _m_a_l_l_o_c() failed.
  284.  
  285.      _X_L_A_T_E__T_B__S_T_A_T_U_S__P_R_O__C_O_N__T_A_B_L_E__M_I_S_M_A_T_C_H
  286.              The _c_o_m_p_o_s_e__w_i_t_h__t_a_b_l_e and the table being created are not both
  287.              64bit or both 32 bit. Instead one is marked as a 32 bit
  288.              translation table and the other is 64 bit.
  289.  
  290.      In addition, if the _c_o_m_p_o_s_e__w_i_t_h__t_a_b_l_e is non-null then any error which
  291.      might be returned by _x_l_a_t_e__g_e_t__i_n_f_o() on the _c_o_m_p_o_s_e__w_i_t_h__t_a_b_l_e may be
  292.      returned.
  293.  
  294. CCCCAAAAVVVVEEEEAAAATTTTSSSS
  295.      Any register information in a table-to-be-composed-with that contains a
  296.      DW_CFA_set_loc or DW_CFA_advance_loc operation is not updated or
  297.      corrected by the library at present: this is a bug.
  298.  
  299.      If an xlate section is created in an Elf file, it is required to have at
  300.      least one range record. An xlate section without at least one range is
  301.      illegal (and the effect is undefined).
  302.  
  303. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  304.      libelfutil(5), xlate(4), xlate_pro_add_info(3e),
  305.      xlate_pro_add_reg_info(3e), xlate_pro_add_range(3e),
  306.      xlate_pro_disk_header(3e), xlate_pro_disk_next_block(3e),
  307.      xlate_init_fd(3e), xlate_pro_finish(3e)
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.                                                                         PPPPaaaaggggeeee 5555
  327.  
  328.  
  329.  
  330.